chore(docs): unify patterns/ naming to NN-slug[-walkthrough].md#518
Merged
Conversation
Patterns 1-5 carried `pattern-N-slug.md` while 7-13 used the lexsort- stable `NN-slug.md` prefix. Pattern #2 had both an engineering design spec (`02-ib-link-flap.md`) AND an operator walkthrough (`pattern-2-ib-link-flap.md`) — distinct doc types, not duplicates. Unify everything under a single numeric-prefix scheme that preserves the spec/walkthrough split as a filename suffix: - `NN-slug.md` = engineering design spec (TDD red-test input) - `NN-slug-walkthrough.md` = operator runbook (symptom -> escalation) Renames (5): pattern-1-nvlink-degradation.md -> 01-nvlink-degradation-walkthrough.md pattern-2-ib-link-flap.md -> 02-ib-link-flap-walkthrough.md pattern-3-hbm-ecc.md -> 03-hbm-ecc-walkthrough.md pattern-4-thermal-throttle.md -> 04-thermal-throttle-walkthrough.md pattern-5-pcie-aer.md -> 05-pcie-aer-walkthrough.md Inbound refs updated in 9 files (MILESTONES, NORTHSTARS, prometheus-scrape, RFC-0014, M4b followup, README, 02-ib-link-flap spec, 3 module/pkg/patterns Go files, thermal_throttle replay manifest). README "Filename convention" section now documents the NN-/NN-walkthrough split explicitly. Pattern #2 keeps both files — they cross-reference each other (spec links to walkthrough for operators; walkthrough links to spec for the engineering contract). docs/patterns/README.md tables already reflected this dual-doc reality; this change makes the filenames honest about it. `scripts/recipes-path-check{.sh,_test.sh}` retained — that gate lints commit-subject references to a non-existent `recipes/pattern-N/` *directory* (issue #427) and is unrelated to `docs/patterns/` filenames. Pre-change `make doc-check`: exit 0 (217 anchors + 1105 md links). Post-change `make doc-check`: exit 0 (same counts; zero broken refs). Signed-off-by: Tri Lam <tree@lumalabs.ai>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Patterns 1-5 in
docs/patterns/carriedpattern-N-slug.mdwhilepatterns 7-13 used the lexsort-stable
NN-slug.mdprefix — two schemesside-by-side. Pattern #2 carried both an engineering design spec
(
02-ib-link-flap.md) AND an operator walkthrough(
pattern-2-ib-link-flap.md); these look like dup-naming but areintentionally distinct doc types per the
docs/patterns/README.mdtwo-table split (operator walkthroughs vs. design specs / TDD red-test
inputs).
This PR unifies the numeric-prefix scheme across the directory while
preserving the spec/walkthrough type distinction via a filename suffix:
NN-slug.md= engineering design specNN-slug-walkthrough.md= operator-facing runbookRenames (5)
pattern-1-nvlink-degradation.md01-nvlink-degradation-walkthrough.mdpattern-2-ib-link-flap.md02-ib-link-flap-walkthrough.mdpattern-3-hbm-ecc.md03-hbm-ecc-walkthrough.mdpattern-4-thermal-throttle.md04-thermal-throttle-walkthrough.mdpattern-5-pcie-aer.md05-pcie-aer-walkthrough.mdPattern #2 dup investigation (not a dup)
02-ib-link-flap.md(engineering design spec) andpattern-2-ib-link-flap.md(operator walkthrough with PromQL alerteach other.
docs/patterns/README.mdalready lists them in separatetables (operator walkthroughs vs design specs). Both retained;
walkthrough renamed to
02-ib-link-flap-walkthrough.mdper theunified convention.
recipes-path-check*.shretained (not the dup-scheme validator)The original task plan flagged
scripts/recipes-path-check.sh+_test.shfor deletion as "the validator policing both schemes".On inspection: those scripts implement the issue #427 convention
gate that lints commit subjects / PR titles for references to a
non-existent
recipes/pattern-N/directory layout. They havenothing to do with
docs/patterns/filenames. Retained.Inbound-ref updates (9 files)
docs/MILESTONES.md,docs/NORTHSTARS.mddocs/integrations/prometheus-scrape.mddocs/rfcs/0014-metrics-to-logs-pattern-input.mddocs/followups/M4b.md(forward-ref to planned14-pod-evicted-walkthrough.md)docs/patterns/README.md(table rows + new "Filename convention"section documenting the NN- / NN-walkthrough split)
docs/patterns/02-ib-link-flap.md(spec's cross-link to itswalkthrough)
module/pkg/patterns/{hbm_ecc,thermal_throttle,pcie_aer}.go(doc-comment references)
module/pkg/replay/thermal_throttle/canonical/manifest.json(replay-fixture description text)
Why this shape (vs collapsing both schemes into one)
The original task framing assumed the two schemes were unintended
divergence — but the README's two-table layout treats them as a
deliberate audience split (engineering TDD-spec readers vs.
operators triaging incidents). Collapsing the walkthroughs into the
spec namespace would have destroyed that signal. The
-walkthroughsuffix preserves the semantic distinction whilegiving the directory the lexsort-stable numeric prefix the task
wanted.
Test plan
make doc-checkexit 0 pre-change (217 anchors + 1105markdown links + 239 non-md intra-repo links resolve)
make doc-checkexit 0 post-change (same counts; zerobroken refs introduced)
rg 'pattern-[1-5]-' docs/ install/ .github/ module/ scripts/returns only in-page heading anchors (
#pattern-2--…,#m17-pattern-1-…), no stale filename refsattribute-namespace-checkclean (100attributes documented),
slo-rules-check13 rules OK,chart-appversion-checkmatches, all module verify passno-autoupdate-check_testclean